home *** CD-ROM | disk | FTP | other *** search
/ Aminet 6 / Aminet 6 - June 1995.iso / Aminet / dev / e / sortobj.lha / sortobj.readme < prev    next >
Encoding:
Text File  |  1995-02-11  |  7.4 KB  |  241 lines
  1. Short: Abstract sortobj object for Amiga E
  2. Type: dev/e
  3. Author: Joseph E. Van Riper III
  4. Uploader: jvanriper@uncavx.unca.edu
  5. Long:
  6.  
  7. SortObj for Amiga E
  8.  
  9. This set of objects was created by Trey Van Riper of the
  10. Cheese Olfactory Workshop for use with Amiga E.  Wear it in
  11. good health.
  12.  
  13. This archive has SortObj, String, Integer, and Address.
  14.  
  15. PURPOSE
  16. -------
  17.  
  18. To supply the Amiga E community with an extensible OT class
  19. that might help provide for some extreme functionality in
  20. the future through reuse (for example, I will very likely
  21. create a sorted list class based on this object class) I
  22. took the trouble to create SortObj.
  23.  
  24. The basic idea behind 'SortObj' is to have a single object
  25. from which other objects can be derived that might allow for
  26. sorting in a list or somesuch.  I have not yet made such a
  27. list, but these objects will still be useful to OT
  28. developers working in Amiga E.
  29.  
  30. NOTE: As this is an abstract class, it's extremely
  31. low-level.  Initially, this object looks on the face of it
  32. to be darned useless, but as people start deriving more
  33. objects from this one, its flexibility will become more
  34. obvious.
  35.  
  36. I am hoping this will help encourage people to release OT
  37. objects to help extend Amiga E's usefulness.
  38.  
  39. HOW TO USE
  40. ----------
  41.  
  42. Well.. I suppose I'd best give the SortObj ShowModule output
  43. first:
  44.  
  45. ShowModule v1.9 (c) 1992 $#%!
  46. now showing: "sortobj.m"
  47. NOTE: don't use this output in your code, use the module instead.
  48.  
  49. /* this module contains 620 bytes of code! */
  50.  
  51. (---) OBJECT sortobj
  52.         new(a)
  53.         opts(a)
  54.         init()
  55.         lt(a)
  56.         gt(a)
  57.         et(a)
  58.         le(a)
  59.         ge(a)
  60.         ne(a)
  61.         cmp(a)
  62.         set(a)
  63.         write()
  64.         get()
  65.     id()
  66.         end()
  67. (---) ENDOBJECT     /* SIZEOF=4 */
  68.  
  69. -- new(a)
  70.  
  71.    This method is intended to be an intializer.  You can
  72.    pass options to it; I would recommend one passes an Amiga
  73.    E list rather than a simple value; this will help keep
  74.    your code extensible.  Basically, one shouldn't have to
  75.    worry about creating their own new() methods as this one
  76.    calls 'init()' and 'opts()'.
  77.  
  78. -- opts(a)
  79.  
  80.    This method allows you to pass special options to the
  81.    object, in case your object requires several things to be
  82.    set at various values (examine the Address object).
  83.  
  84. -- init()
  85.  
  86.    This method is intended to help you initialize the
  87.    object, in case it needs it.  Maybe you need to NEW some
  88.    pointers or something.
  89.  
  90. -- cmp(a)
  91.  
  92.    This method is VERY important... to get the most out of
  93.    sortobj, you will want to define this.  Basically, this
  94.    should perform a comparison between something within your
  95.    object, and something within object 'a' (which should be
  96.    the same as your own object).
  97.  
  98.    Not that the above makes a lot of sense.
  99.  
  100.    Generally, 'a' is supposed to be an instance of the
  101.    object you're creating.  'cmp()' is supposed to compare
  102.    something within that instance with something inside your
  103.    'self' instance.
  104.  
  105.    It should return '1' if the 'self' value is greater than
  106.    the 'a' value, '0' if the two are equal, and '-1' if
  107.    'self' is less than the 'a' value.
  108.  
  109.    Then, a whole bunch of other functions will become
  110.    enabled for your procedure... lt()/gt()/le()/ge()/ne()/et()
  111.    will all instantly start working for you.
  112.  
  113.    I recommend you try to make this function work as quickly
  114.    as possible, as in some cases it might be called twice
  115.    (eg ge() and le()).
  116.  
  117. -- lt(a)
  118.  
  119.    This tests to see if self is less than a.
  120.  
  121. -- gt(a)
  122.  
  123.    This tests to see if self is greater than a.
  124.  
  125. -- et(a)
  126.  
  127.    This tests to see if self is equal to a.
  128.  
  129. -- le(a)
  130.  
  131.    This tests to see if self is less than or equal to a.
  132.  
  133. -- ge(a)
  134.  
  135.    This tests to see if self is greater than or equal to a.
  136.  
  137. -- ne(a)
  138.  
  139.    This tests to see if self is not equal to a.
  140.  
  141. -- write()
  142.  
  143.    This method should return a string to be written by
  144.    someone else.  Perhaps, in the far future, this class
  145.    could be extended by creating an output object that could
  146.    be used by sortobj or something.. in the meantime, you
  147.    can try using this.
  148.  
  149.    Basically, make sure this method returns something you
  150.    could WriteF().
  151.  
  152. -- get()
  153.  
  154.    This method should return the data within the object.
  155.    This isn't exactly easy to judge in the case of objects
  156.    with multiple members (such as the Address object), but
  157.    its useful for such things as strings and integers.
  158.    Perhaps this could return an OBJECT with normal pointers
  159.    to strings and stuff like that... it'll have to be your
  160.    own call how to use it, but you hopefully get the general
  161.    drift.  Use the other objects derived from sortobj as a
  162.    guide.
  163.  
  164. -- id()
  165.  
  166.    This method returns a number describing the kind of
  167.    object it is.  This can be handy for making lists of
  168.    objects of unknown types.
  169.  
  170. -- end()
  171.  
  172.    Of course, this is the deallocator.  This function will
  173.    be called when someone ENDs the object, so it should be
  174.    useful for something <grin>.
  175.  
  176. SO WHAT, WHO CARES
  177. ------------------
  178.  
  179. I know it doesn't seem like such a big deal to have these
  180. objects, especially since I'm not yet supplying a sorted
  181. list, but consider how useful this would be when used with
  182. something like queuestack (yeah, I know, cheap
  183. advertisement, but hey, it's a cheap product)... then again,
  184. someone else might beat me to the creation of an object
  185. oriented sorted list!
  186.  
  187. You could store pointers to different kinds of sortobjs
  188. within queuestack, dropping them into the queuestack
  189. willy-nilly, without any idea what they might be, then pull
  190. them out again as needed, id()ing them to figure out what
  191. they are.
  192.  
  193. You could even iterate through the queuestack, write()ing
  194. the values to some kind of variable to be printed out in a
  195. WriteF() or something, without having to worry about what
  196. the object in the queuestack is!
  197.  
  198. I've taken the trouble to provide you with a string and
  199. integer object as subclasses of sortobj, as well as an
  200. example of a more complex object 'address'.  Still to be
  201. written are a float and fraction object.
  202.  
  203. The string and integer classes need further work; the string
  204. class should have some means by which someone could append
  205. new strings to it, as well as number conversions and all
  206. that happy stuff (basically, all the various Amiga
  207. Efunctions put into the class itself), while the integer
  208. object could use various functions to handle arithmatic
  209. matters.
  210.  
  211. In fact, the entire integer class will be reworked in the
  212. future to be derived from a higher abstract class 'number' that
  213. I'm going to create sometime later... but I wanted to get a
  214. quick version out in the meantime.
  215.  
  216. DISTRIBUTION
  217. ------------
  218.  
  219. You are granted full rights to use and distribute this.
  220. I am not requiring money for its use.  In fact, I encourage
  221. as many people as possible to use this, and to possibly
  222. extend this as much as possible.  Hell, fix any screwup you
  223. find!
  224.  
  225. Basically, this is Public Domain; even the source has been
  226. made available so you can have yet another example of OT
  227. programming.  I ask that you do not modify the source code
  228. under my name; let me be responsible for my own mistakes,
  229. nobody else's.  I also ask you do not take credit for work
  230. I've done; OT programming seems to be tricky for some folks
  231. to handle, and I want to be sure to get the credit where
  232. it's due.
  233.  
  234. Consider this a contribution to the Amiga E community to
  235. encourage the development of object tools in the Amiga E
  236. language.
  237.  
  238. As ever, Wouter van Ootmerson has full permission to include
  239. this in his next release of Amiga E, as he sees fit, without
  240. having to pay me anything but credit.
  241.